---
layout: base
title: Getting Started
---

<header class="jumbotron subhead" id="overview">
  <div class="container">
    <h3>Getting started with Sugar ORM</h3>
  </div>
</header>

<div class="container">
  <div class="row">
    <div class="col-md-3">
      <div id="sidebar" role="complementary" data-spy="affix" data-offset-top="80">
        <ul class="nav sidebar">
          <li class="active"><a href="#download-sugar">Download</a></li>
          <li><a href="#configuration">Configuration</a></li>
          <li><a href="#entities">Entities</a></li>
          <li><a href="#usage">Usage</a></li>
        </ul>
      </div>
    </div>
    <div class="col-md-9">
      <section id="download-sugar">
        <div class="page-header">
          <h1>1. Download</h1>
        </div>
        <p class="lead">Gradle:</p>

        <div class="row">


{% highlight xml %}
compile 'com.github.satyan:sugar:1.3'
{% endhighlight %}
        
          
        </div>
      </section>

        <section id="configuration">
          <div class="page-header">
            <h1>2. Configuration.</h1>
          </div>
          <p class="lead"> It requires minimal configuration.</p><p> All you need to do is, specify SugarApp as your application class in AndroidManifest.xml. You do that by changing the <code>android:name</code> attribute of the <code>application</code> tag.</p>

          <div class="bs-docs-example">
            AndroidManifest.xml

{% highlight xml %}
<application android:label="@string/app_name" android:icon="@drawable/icon"
android:name="com.orm.SugarApp">
.
.
<meta-data android:name="DATABASE" android:value="sugar_example.db" />
<meta-data android:name="VERSION" android:value="2" />
<meta-data android:name="QUERY_LOG" android:value="true" />
<meta-data android:name="DOMAIN_PACKAGE_NAME" android:value="com.example" />
.
.
</application>
{% endhighlight %}
          </div>

          <p>The meta-data tags are all optional and serve the following purpose:</p>
          <table class="table table-bordered table-striped">
            <thead>
              <tr>
                <th>Metadata</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td>
                  <code>DATABASE</code>
                </td>
                <td>Name of the generated sqlite database file. eg: app_name.db</td>
              </tr>
              <tr>
                <td>
                  <code>VERSION</code>
                </td>
                <td>Version of your database schema.</td>
              </tr>
              <tr>
                <td>
                  <code>QUERY_LOG</code>
                </td>
                <td>Logs the generated Select queries.</td>
              </tr>
              <tr>
                <td>
                  <code>DOMAIN_PACKAGE_NAME</code>
                </td>
                <td>Specify a package name where your domain/entity classes are present. This helps in smoother table creation.</td>
              </tr>
            </tbody>
          </table>
        </section>

        <section id="entities">
          <div class="page-header">
            <h1>3. Entities</h1>
          </div>
          <p class="lead">Extend <code>SugarRecord</code> for all the classes that you need persisted. <strong>That's it.</strong> Sugar takes care of table creation for you.</p><p> <strong>Note: Please retain the default constructor.</strong></p>

          <div class="bs-docs-example">
{% highlight java %}
public class Book extends SugarRecord<Book> {
  String title;
  String edition;

  public Book(){
  }

  public Book(String title, String edition){
    this.title = title;
    this.edition = edition;
  }
}
{% endhighlight %}
          </div>
        </section>

        <section id="usage">
          <div class="page-header">
            <h1>4. Basic Usage</h1>
          </div>
          <p class="lead">Performing CRUD operations are very simple. Functions like <code>save()</code>, <code>delete()</code> and <code>findById(..)</code> are provided to make the work easy.</p>
          <div class="bs-docs-example">
            Save Entity:

{% highlight java %}
Book book = new Book(ctx, "Title here", "2nd edition")
book.save();
{% endhighlight %}

            Load Entity:

{% highlight java %}
Book book = Book.findById(Book.class, 1);
{% endhighlight %}

            Update Entity:

{% highlight java %}
Book book = Book.findById(Book.class, 1);
book.title = "updated title here"; // modify the values
book.edition = "3rd edition";
book.save(); // updates the previous entry with new values.
{% endhighlight %}

            Delete Entity:

{% highlight java %}
Book book = Book.findById(Book.class, 1);
book.delete();
{% endhighlight %}


            Bulk Operations:

{% highlight java %}
List<Book> books = Book.listAll(Book.class);

Book.deleteAll(Book.class);
{% endhighlight %}
          </div>
        </section>

    </div>
  </div>
</div>
